/** 
 * Copyright (C) 2012 Foxit Corporation.
 * All Rights Reserved.
 *
 * The following code is copyrighted and contains proprietary information and trade secrets of Foxit Corporation. 
 * You can only redistribute files listed below to customers of your application, under a written SDK license agreement with Foxit. 
 * You cannot distribute any part of the SDK to general public, even with a SDK license agreement. 
 * Without SDK license agreement, you cannot redistribute anything.
 * 
 * @file	fpdffont.h
 * @brief	Header file for the PDF Font module.
 * @details	The PDF Font module offers methods to do some operations on PDF font object.
 *			<br>
 *			Following the specification of PDF, users can get the PDF font object information.
 * @note	If you want to purchase Foxit PDF SDK license and use ANY of the following functions, please
 *			request for enabling PDF Font module explicitly. 
 */

/** 
 * @addtogroup FGSPDFFONT PDF Font
 * @brief Methods in this module are included in fpdffont.h
 */

/** @{*/
#ifndef __FGSPDFFONT__
#define __FGSPDFFONT__

#include "fpdfbase.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
* @brief Retrieve the face name of the font and return the name in a string.
* 
* @param[in] font	Reference to the font object.
* 
* @return	The name of the font if success, else NULL. 
*/
CFStringRef FGSPDFFontCopyFontName(FGSPDFFontRef font);

/**
* @brief Get the value of the flags entry in a font descriptor.
* 
* @param[in] font	Reference to the font object.
*
* @note   The value of the flags entry in a font descriptor is an unsigned 32-bit<br>
*         integer containing flags specifying various characteristics of the font.
*         
* @return ::kFGSErrorSuccess means successfully.<br>
*			For more definitions please see enum definitions <b>FGSErrorRet</b>.
*/
SInt32 FGSPDFFontGetFlags(FGSPDFFontRef font);

/**
* @brief Get the font bounding box.
* 
* @param[in] font	Reference to the font object.	
* 
* @return A CGRect object receives the font bounding box.
*/
CGRect FGSPDFFontGetBBox(FGSPDFFontRef font);

/**
* @brief Get the special character bounding box of a font object.
* 
* @param[in] font		Reference to the font object.
* @param[in] char_code	The character code.
* 
* @return A CGRect object receives the special character bounding box of a font object.
*/
CGRect FGSPDFFontGetCharBBox(FGSPDFFontRef font, UInt32 char_code);

/**
* @brief Get the special character width of a font object.
* 
* @param[in] font		Reference to the font object.		
* @param[in] char_code	The character code.	
* 
* @return The special character width of a font object.
*/
UInt32 FGSPDFFontGetCharWidth(FGSPDFFontRef font, UInt32 char_code);
    
/**
* @brief Get the unicode value from a character code.
* 
* @param[in] font		Reference to the font object.		
* @param[in] char_code	The character code.	
* 
* @return The special unicode value.
*/
SInt16 FGSPDFFontGetUnicode(FGSPDFFontRef font, UInt32 char_code);

/**
* @brief Get the character size in the font.
* 
* @param[in] font		Reference to the font object.	
* @param[in] char_code	The character code.	
* 
* @return The value of the character size.
*/
SInt32 FGSPDFFontGetCharSize(FGSPDFFontRef font, UInt32 char_code);	

/**
* @brief Get the character code from a unicode value.
* 
* @param[in] font		Reference to the font object.	
* @param[in] unicode	The unicode of a special character.	
* 
* @return The character code value.
*/
UInt32 FGSPDFFontGetCharCode(FGSPDFFontRef font, UInt16 unicode);

/**
* @brief Get the descent value in the font.
* 
* @param[in] font	Reference to the font object.	
* @note   The descent value describes the maximum depth below the baseline 
* 		  reached by glyphs in this font. The value is a negative number.
* 
* @return The descent value.
*/
SInt32 FGSPDFFontGetFontDescent(FGSPDFFontRef font);

/**
* @brief Get the ascent value in the font.
* 
* @param[in] font	Reference to the font object.		
* @note   The ascent value describes the maximum height above the baseline reached 
*         by glyphs in this font, excluding the height of glyphs for accented characters.
*         
* @return The ascent value.
*/
SInt32 FGSPDFFontRefGetFontAscent(FGSPDFFontRef font);

/**
 * @brief FGSPDF Font Encoding Flag
 */
enum {
    /** Built-in encoding.*/
    kPDFFontEncodingDefault             = 0,
    /** WinAnsiEncoding.*/
    kPDFFontEncodingWinAnsi             = 1,
    /** MacRomanEncoding.*/
    kPDFFontEncodingMacRoman            = 2,	
    /** MacExpertEncoding.*/
    kPDFFontEncodingMacExpert           = 3,	
    /** StandardEncoding. Adobe standard encoding. */
    kPDFFontEncodingStandard            = 4,    
    /** Adobe symbol encoding. */
    kPDFFontEncodingAdobeSymbol         = 5,
    /** ZapfDingbats encoding. */
    kPDFFontEncodingZapfDingbarts       = 6,
    /** PDFDocEncoding. */
    kPDFFontEncodingPdfDoc              = 7,
    /** Microsoft symbol encoding. */
    kPDFFontEncodingMsSymbol            = 8,
    /** Unicode. */
    kPDFFontEncodingUnicode             = 9,
};
/** @brief Alias of enumeration for font encoding flag. */
typedef UInt32 FGSPDFFontEncoding;

/**
* @brief Create a standard type font and add the font into the document.
* 
* @param[in] document		Reference to a PDF document. 
* @param[in] font_name		A string that specifies the typeface name of the font. 
* @param[in] encoding		The font encoding defined above.
* 
* @return Reference to the new font object.
*/
FGSPDFFontRef FGSPDFFontAddStandardFont(FGSPDFDocumentRef document, CFStringRef font_name, FGSPDFFontEncoding encoding);

#ifdef __cplusplus
};
#endif

#endif // __FGSPDFFONT__
/**@}*/


